Skip to content

config.md

Latest commit

 

History

History
323 lines (229 loc) · 19.5 KB

config.md

File metadata and controls

323 lines (229 loc) · 19.5 KB
Raw

CSGClaw Configuration

English | 中文

csgclaw serve uses the local config file for server access, bootstrap image selection, sandbox isolation, and optional channels, and it auto-creates missing local state on first run. Agent LLM provider profiles are stored in agent state and managed from the Web UI.

Server Address

listen_addr is the address that the local HTTP server binds to.

advertise_base_url is the base URL that CSGClaw gives to manager and worker boxes so they can call back into the local HTTP server. When it is set, CSGClaw uses it as-is after trimming a trailing slash and does not try to infer a host IP. When it is empty, CSGClaw falls back to an inferred local IPv4 address plus the configured listen port.

Use advertise_base_url when the automatically inferred address is not reachable from BoxLite boxes, such as when you need a LAN address, a tunnel URL, or a host alias.

When it is set, the Web UI login flow also uses it as the trusted public base for the auth callback and post-login return URL. Reverse proxies and sandbox gateways must route <advertise_base_url>/api/v1/auth/callback back to the CSGClaw server.

When the sandbox provider is docker on Docker Desktop, an empty advertise_base_url resolves to http://host.docker.internal:<port> for generated manager and worker runtime config. Set advertise_base_url explicitly when you need a different Docker callback URL.

access_token protects authenticated API routes, including the PicoClaw participant bridge routes. When authentication is enabled, clients must send Authorization: Bearer <access_token>.

no_auth controls whether CSGClaw skips the bearer-token check. The default is false. Set it to true only for trusted local or development environments.

show_upgrade controls whether the Web UI shows upgrade actions. The default is true; set it to false only when the deployment cannot self-upgrade, such as managed Kubernetes environments.

The server derives its active update channel from the running version. Plain versions such as v0.5.0 use the release channel; prerelease, development, local, and otherwise non-plain versions use beta. A version-channel switch from the Web UI is a one-shot installation and is not persisted in config.toml.

String values in config.toml can reference environment variables with ${NAME} or $NAME. CSGClaw expands them when loading the config and keeps the placeholder form when it later rewrites the same value. If an environment variable is not set, it expands to an empty string.

[server]
listen_addr = "0.0.0.0:${PORT}"
advertise_base_url = "http://${IP}:${PORT}"
access_token = "${ACCESS_TOKEN}"
no_auth = false
show_upgrade = true

Model Provider Examples

Local CSGHub-lite

[server]
listen_addr = "0.0.0.0:18080"
advertise_base_url = "http://127.0.0.1:18080"
access_token = "your_access_token"
no_auth = false
show_upgrade = true

[models]
default = "csghub-lite.Qwen/Qwen3-0.6B-GGUF"

[models.providers.csghub-lite]
base_url = "http://127.0.0.1:11435/v1"
api_key = "local"
models = ["Qwen/Qwen3-0.6B-GGUF"]

[bootstrap]
manager_image_override = ""
runtime_kind = "picoclaw_sandbox"

[sandbox]
provider = "boxlite"

Remote LLM API

[server]
listen_addr = "0.0.0.0:18080"
advertise_base_url = "http://127.0.0.1:18080"
access_token = "your_access_token"
no_auth = false
show_upgrade = true

[models]
default = "remote.gpt-5.4"

[models.providers.remote]
base_url = "https://api.openai.com/v1"
api_key = "sk-your-api-key"
models = ["gpt-5.4"]

[bootstrap]
manager_image_override = ""
runtime_kind = "picoclaw_sandbox"

[sandbox]
provider = "boxlite"

Dynamic Codex or Claude Code profiles

[server]
listen_addr = "0.0.0.0:18080"
advertise_base_url = "http://127.0.0.1:18080"
access_token = "your_access_token"
no_auth = false
show_upgrade = true

[bootstrap]
manager_image_override = ""
runtime_kind = "picoclaw_sandbox"

[sandbox]
provider = "boxlite"

Codex and Claude Code profiles are configured in agent state through the Web UI. CSGClaw starts an embedded CLIProxyAPI on a private localhost port at serve time, so static CLIProxy base URLs are not required.

Workers can also select an explicit runtime kind when they are created. The default runtime kind is picoclaw_sandbox. To create a sandboxed OpenClaw worker, use csgclaw agent create --runtime openclaw_sandbox ...; to create a Codex worker, use csgclaw agent create --runtime codex .... The API accepts the same values through runtime_kind on POST /api/v1/agents.

Leave [bootstrap].manager_image_override empty to use the built-in default manager image. Set it only when you need to override that default. The bootstrap manager currently runs on picoclaw_sandbox; openclaw_sandbox is supported for workers, not as the manager runtime.

Auth is also managed locally:

  • Codex auth is imported from ~/.codex/auth.json when available.
  • Claude Code auth is probed from macOS Keychain when available, then falls back to OAuth.
  • At server startup, Codex and Claude Code auth are imported or refreshed into the CSGClaw-managed CLIProxy auth directory using CLIProxy-compatible JSON.
  • Manual login commands are csgclaw model auth login codex and csgclaw model auth login claude-code.
  • CSGCLAW_CLIPROXY_AUTH_DIR overrides the CLIProxy auth directory; the default is ~/.csgclaw/auth.
  • CSGCLAW_CLIPROXY_AUTO_LOGIN=0 disables automatic import/probing.
  • CSGCLAW_CLIPROXY_NO_BROWSER=1 prints OAuth URLs instead of opening a browser.
  • CSGCLAW_CLIPROXY_DISABLE_KEYCHAIN=1 disables Claude Keychain probing.

When a worker uses the Codex runtime, its local state is stored under ~/.csgclaw/agents/<agent-name>/.codex/. The workspace lives at ~/.csgclaw/agents/<agent-name>/.codex/workspace, shell home lives at ~/.csgclaw/agents/<agent-name>/.codex/home, and Codex-managed files such as auth.json, config.toml, stderr.log, and runtime metadata are stored under ~/.csgclaw/agents/<agent-name>/.codex/home. This path is intentionally separate from the sandbox provider home such as ~/.csgclaw/agents/<agent-name>/boxlite.

CSGClaw enables Codex local memories for each Codex runtime, including both memory generation and reuse in later sessions. Memories are isolated per Agent under ~/.csgclaw/agents/<agent-name>/.codex/home/memories/ and are not shared with the host Codex installation or another Agent. Use the Agent Profile page's Memory tab to enable or disable both memory generation and memory reuse; the default is enabled. Treat memory files as generated runtime state and keep required Agent rules in AGENTS.md or checked-in documentation. Recreating a Codex Runtime preserves durable Codex state, including the workspace, native session history and thread mappings, memory files and indexes, goals, optional authentication, plugins, rules, hooks, and the installation ID. Recreation replaces generated configuration and model catalogs, process metadata, queues, logs, temporary files, locks, and shell snapshots. Deleting the Agent still removes its complete Agent home, including memory.

For complete Codex worker profiles, CSGClaw writes ~/.csgclaw/agents/<agent-name>/.codex/home/config.toml with an OpenAI-compatible proxy provider and always sets wire_api = "responses" because the Codex CLI app-server path uses the Responses API. When Codex memory is enabled, CSGClaw sets memories.min_rollout_idle_hours = 1, the minimum supported idle window, so completed room threads become eligible for background extraction sooner. Because Codex skips the currently active thread, CSGClaw forks an invisible checkpoint after a successful room turn, at most once per conversation per hour, without changing the thread that continues serving the room. After the checkpoint has been idle for one hour, CSGClaw sends an invisible maintenance turn on the Runtime's private maintenance thread so memory extraction can run even when the user never opens another room. Checkpoint and maintenance output is not delivered to the room, but the background extraction and consolidation requests consume model usage and may still be deferred by Codex's rate-limit guard. After a successful maintenance trigger, CSGClaw retains the checkpoint for 30 minutes so the asynchronous memory pipeline can finish, then deletes it to keep the Codex thread store bounded. The generated provider uses HTTP Responses rather than Responses WebSocket. If the upstream provider reports the Responses endpoint as unsupported, or the embedded CLIProxy Codex/ClaudeCode Responses backend returns a 5xx for a text-only request, CSGClaw keeps the Codex-side Responses configuration and falls back to upstream chat completions behind the proxy. Runtime validation probes the chat completions fallback when Responses is unsupported, so an invalid base URL cannot pass startup merely because /responses returned 404. When an in-use model provider's base URL, API key, or headers change, CSGClaw checks the new transport before saving it and preserves the previous working configuration if the check fails. The raw upstream API key is not written to this file; it is injected into the runtime environment through env_key = "OPENAI_API_KEY".

When a worker uses the Codex runtime, CSGClaw launches the Codex CLI bundled next to the CSGClaw executable with codex app-server --listen stdio://. It does not use PATH, CSGCLAW_CODEX_PATH, or CSGCLAW_CODEX_ACP_PATH; reinstall CSGClaw if that bundled executable is missing.

OpenClaw Runtime

CSGClaw defaults to PicoClaw for the bootstrap manager. To create a sandboxed OpenClaw worker, set the worker runtime explicitly:

csgclaw agent create --name alice --runtime openclaw_sandbox

The recommended image shape is a slim OpenClaw base image with CSGClaw-managed plugins baked under /home/node/openclaw-plugins (for example, csgclaw-extension and external channel plugins). Runtime state still comes from ~/.csgclaw/agents/<agent>/.openclaw/openclaw.json; do not mount an empty host directory over /home/node/openclaw-plugins, because that hides baked plugins.

Generated OpenClaw bridge models use conservative metadata for plain OpenAI-compatible profiles. They default to openai-completions, input: ["text"], no reasoning effort support, and no agents.defaults.thinkingDefault value. This prevents OpenClaw from sending image or reasoning payloads to providers that have not advertised those capabilities through CSGClaw. Agent profiles persist one reasoning_effort strategy: auto, none, minimal, low, medium, high, or xhigh. Missing legacy values normalize to auto; existing explicit values remain unchanged. For OpenClaw, auto omits thinkingDefault, explicit efforts set it, and none maps it to off. CSGClaw also sets reasoningDefault: "stream" unless reasoning is disabled so the channel plugin receives public reasoning callbacks; models that emit no reasoning continue through the normal reply flow. With a Codex profile, CSGClaw declares the bridge model as openai-codex-responses, enables input: ["text", "image"], writes the minimal, low, medium, high, and xhigh reasoning levels, and adds streaming usage compatibility metadata. The Codex reasoningEffortMap passes these levels through by name.

Sandbox Providers

CSGClaw runs Workers through the configured sandbox provider. Supported built-in providers are:

  • boxlite: deprecated compatibility provider for legacy development environments; runs Workers through the local boxlite CLI when explicitly configured.
  • docker: runs Workers through the local Docker CLI.
  • csghub: runs Workers in the remote CSGHub sandbox. This is currently supported only in AgenticHub.

Official bundles use one of these layouts:

  • csgclaw/bin/csgclaw plus csgclaw/bin/boxlite
  • csgclaw/bin/csgclaw only

If [sandbox].provider is omitted or empty, CSGClaw defaults to docker.

That means a generated config can keep the provider empty to follow the default:

[sandbox]
provider = ""

You can always override the default explicitly:

[sandbox]
provider = "boxlite"
[sandbox]
provider = "docker"

For provider = "boxlite", CSGClaw resolves the bundled sibling boxlite binary next to csgclaw first, then falls back to PATH if that bundle is missing. BoxLite is deprecated and no longer the recommended provider, but explicit legacy configurations remain supported for development use. CSGClaw does not silently rewrite them. If BoxLite is unavailable, the server and host-only runtimes still start; the first BoxLite-backed operation returns an actionable error recommending Docker.

For provider = "docker", Docker executable availability is checked when an operation actually opens the provider, such as creating or starting a sandbox Agent or listing local images. The server and a host-only manager can therefore start without Docker installed; the first Docker-backed operation still returns an actionable error.

debian_registries_override controls where BoxLite pulls debian:bookworm-slim when you need to override the built-in default order. If omitted or empty, CSGClaw uses harbor.opencsg.com then docker.io. When CSGClaw writes config.toml, it keeps this field visible as an empty array so it can be edited in place:

[sandbox]
provider = "boxlite"
debian_registries_override = []

CSGClaw passes an explicit --home to the BoxLite CLI for each agent, using the fixed per-agent runtime home ~/.csgclaw/agents/<agent-id>/boxlite. That explicit home takes precedence over BOXLITE_HOME for CSGClaw-managed sandboxes, while BOXLITE_HOME still applies when you run boxlite manually without --home.

The boxlite provider does not need a vendored Go SDK at runtime. Current source builds and release packaging use the same BoxLite CLI-backed integration:

  • make build, make test, make run, and make package all use the standard boxlite path.
  • boxlite remains the built-in BoxLite sandbox provider, alongside other non-BoxLite providers such as csghub.

To use Docker as the sandbox provider:

[sandbox]
provider = "docker"

When provider = "docker", CSGClaw runs the local docker CLI. By default it resolves docker from PATH. If you need a specific binary, set docker_cli_path:

[sandbox]
provider = "docker"
docker_cli_path = "/usr/local/bin/docker"

Current platform expectations:

  • An empty provider resolves to docker.
  • Windows users should have Docker installed and reachable on PATH, or set [sandbox].docker_cli_path explicitly.

Hub Configuration

CSGClaw reads templates from the built-in, local, and official registries. Only built-in and local registries are configurable in config.toml; the official remote registry is managed by the application.

When [hub] is omitted, CSGClaw enables builtin (read-only), local (writable publish target at ~/.csgclaw/hub), and the application-managed official remote. The official remote is always resolved from the current OpenCSG login environment at request time: production uses https://hub.opencsg.com, and staging uses https://opencsg-stg.com.

[hub]
default_registry = "builtin"
default_publish_registry = "local"
[[hub.registries]]
name = "builtin"
kind = "builtin"
enabled = true

[[hub.registries]]
name = "local"
kind = "local"
path = "~/.csgclaw/hub"
enabled = true

Field behavior:

  • default_registry selects the default source registry when a command needs one registry context.
  • default_publish_registry selects the default publish target when a command does not pass a registry explicitly.
  • name is the registry identifier used by CLI and API flows.
  • kind is builtin or local in config.toml.
  • path is used by local registries.
  • enabled controls whether the registry participates in hub operations. If omitted, it defaults to true.

The built-in registry is read-only; local is the configurable writable target. The Web UI publishes to the application-managed official registry for the currently signed-in OpenCSG site and disables that flow when no OpenCSG account is signed in. Remote entries in [[hub.registries]] are ignored and removed the next time CSGClaw saves config.toml.

When signed in, the current login site and access token select and authorize the official registry, even when managed environment variables are present. Without an interactive login, CSGHUB_API_BASE_URL selects the official registry and CSGHUB_USER_TOKEN authorizes private template reads; when the base URL is omitted, CSGClaw falls back to the production registry. TEMPLATE_ID should contain the template repository path in <namespace>/<name> form.

The old template Hub URL https://csgclaw.opencsg.com and custom remote registry URLs in config.toml are no longer used. The official registry follows the login environment.

Skill registry configuration

csgclaw skill uses two skill registries by default:

  • opencsg (primary): https://claw.opencsg.com
  • clawhub (official): https://clawhub.ai

skill search queries opencsg first and returns immediately when there are hits; it only queries clawhub.ai when opencsg returns no results.

Use --registry opencsg or --registry clawhub on get / install to target one registry. Omit it to try opencsg first, then clawhub.

The Web UI requests the remote Skill catalog through the local CSGClaw Server. The server resolves the OpenCSG Hub from the active login environment: production uses https://hub.opencsg.com, and staging uses https://opencsg-stg.com; an explicitly configured official Hub URL is preserved. The CLI csgclaw skill registry remains separate and uses https://claw.opencsg.com for both production and staging logins.

Supported registry APIs:

  • GET /api/v1/search — csgclaw skill search
  • GET /api/v1/skills/:slug — csgclaw skill get (includes versions[] on OpenCSG)
  • GET /api/v1/skills/:slug/versions — csgclaw skill versions (paginated on clawhub.ai; OpenCSG falls back to versions[] on get)
  • GET /api/v1/skills/:slug/versions/:version — csgclaw skill get --version
  • GET /api/v1/download/:slug or GET /api/v1/download?slug= — install download

Browse skills with search; there is no catalog list endpoint on the current registry.

[skill]
base_url = "https://claw.opencsg.com"
official_base_url = "https://clawhub.ai"
token = "${SKILL_TOKEN}"
non_suspicious_only = true
  • base_url is the primary (opencsg) registry. You can also set SKILL_BASE_URL (legacy: CLAWHUB_BASE_URL).
  • official_base_url is the secondary (clawhub.ai) registry. Defaults to https://clawhub.ai. Set to "" to disable dual-registry search. Override with SKILL_OFFICIAL_BASE_URL (legacy: CLAWHUB_OFFICIAL_BASE_URL).
  • token is optional for read-only commands and required for future publish flows. You can also set SKILL_TOKEN (legacy: CLAWHUB_TOKEN).
  • The legacy [clawhub] section is still read for backward compatibility.
  • non_suspicious_only defaults to true when omitted.

Channel Configuration

Channel integration is optional. CSGClaw works with the built-in Web UI by default, and you only need channel config when you want to connect external messaging platforms such as Feishu.

Keep config.toml focused on shared server, model, bootstrap, and sandbox settings. Feishu credentials live on Feishu participants in ~/.csgclaw/im/participants.json and are written with csgclaw-cli participant bind; legacy [channels.feishu] blocks and channels/feishu.toml are not read by the participant-backed flow.

For detailed field definitions and examples, see Feishu Channel Configuration.