@laitszkin/apollo-toolkit 2.5.0 → 2.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,191 @@
1
+ # Official Marginfi Development Notes
2
+
3
+ Checked against official marginfi docs on 2026-03-20.
4
+
5
+ ## Canonical official sources
6
+
7
+ - Docs home: `https://docs.marginfi.com/`
8
+ - TypeScript SDK docs: `https://docs.marginfi.com/ts-sdk`
9
+ - Rust CLI docs: `https://docs.marginfi.com/rust-sdk`
10
+ - Protocol design: `https://docs.marginfi.com/protocol-design`
11
+ - Program docs (`mfi-v2`): `https://docs.marginfi.com/mfi-v2`
12
+ - The Arena docs: `https://docs.marginfi.com/the-arena`
13
+
14
+ ## 1. Protocol model to keep in mind
15
+
16
+ marginfi is a pooled-balance lending protocol on Solana. The main developer objects are:
17
+
18
+ - `MarginfiGroup`: protocol-wide configuration and shared state for a deployment.
19
+ - `Bank`: the per-asset pool with oracle config, risk weights, limits, and utilization-driven rates.
20
+ - `MarginfiAccount`: the user's margin account that holds deposits and liabilities across banks.
21
+
22
+ Important protocol-design facts from the official docs:
23
+
24
+ - Risk is controlled by asset weights, liability weights, and loan-to-value style constraints.
25
+ - Oracles come from Pyth and Switchboard, with confidence and staleness checks before prices are accepted.
26
+ - Docs mention a maximum oracle staleness of 60 seconds and a 95% confidence interval requirement.
27
+ - Pyth EMA pricing is described as roughly 5,921 slots (about 1 hour) for smoothing.
28
+ - Interest rates use a two-segment utilization curve: rates rise with utilization, then increase more aggressively after the optimal-utilization threshold.
29
+ - Asset risk tiers include collateral-style assets, borrow-only assets, and isolated assets.
30
+
31
+ Use these facts when reasoning about account health, liquidations, and bank config; do not reduce health checks to simple spot-price math.
32
+
33
+ ## 2. Official addresses and environments
34
+
35
+ The official docs currently expose these environment values across the docs home and protocol-design pages:
36
+
37
+ - Mainnet program: `MFv2hWf31Z9kbCa1snEPYctwafyhdvnV7FZnsebVacA`
38
+ - Mainnet group: `FCPfpHAjHn9R6vWQbtyzcN8PjjobJABQj9rChmC6Cv5j`
39
+ - Staging program: `stag8sTKDs4Df2RehcgddBVAtDx6gbDp7YkA94R6HvK`
40
+ - Staging group: `2rpQwP4ofD6P2AojSeyjc9kUCzjscX4oMtd2N4eySe7W`
41
+
42
+ Treat these as time-sensitive. Re-check the docs page before hardcoding them in new work.
43
+
44
+ ## 3. TypeScript SDK essentials
45
+
46
+ Official docs point to the npm package `@mrgnlabs/marginfi-client-v2` plus `@mrgnlabs/mrgn-common` helpers.
47
+
48
+ Core setup flow from the docs:
49
+
50
+ 1. Create a Solana `Connection`.
51
+ 2. Build a wallet adapter or `NodeWallet`.
52
+ 3. Load `getConfig("production")` or another environment config.
53
+ 4. Call `MarginfiClient.fetch(config, wallet, connection)`.
54
+ 5. Fetch existing marginfi accounts for the authority, or create one.
55
+ 6. Resolve the target bank, then perform actions.
56
+
57
+ Minimal example pattern:
58
+
59
+ ```ts
60
+ import { Connection } from "@solana/web3.js";
61
+ import { MarginfiClient, getConfig } from "@mrgnlabs/marginfi-client-v2";
62
+ import { NodeWallet } from "@mrgnlabs/mrgn-common";
63
+
64
+ const connection = new Connection(process.env.RPC_URL!, "confirmed");
65
+ const wallet = NodeWallet.local();
66
+ const config = getConfig("production");
67
+ const client = await MarginfiClient.fetch(config, wallet, connection);
68
+
69
+ const accounts = await client.getMarginfiAccountsForAuthority();
70
+ const account = accounts[0] ?? (await client.createMarginfiAccount());
71
+ const bank = client.getBankByTokenSymbol("SOL");
72
+ if (!bank) throw new Error("SOL bank not found");
73
+
74
+ await account.deposit(1, bank.address);
75
+ ```
76
+
77
+ Useful SDK objects and methods called out in the docs:
78
+
79
+ - Client bootstrap: `MarginfiClient.fetch`, `getConfig`
80
+ - Bank lookup: `getBankByTokenSymbol`, `getBankByMint`, `getBankByPk`
81
+ - Oracle helpers: `getOraclePriceByBank`
82
+ - Account discovery: `getMarginfiAccountsForAuthority`
83
+ - Account creation: `createMarginfiAccount`
84
+ - Permissionless-bank support: `createLendingPool`
85
+ - Transaction helper: `processTransaction`
86
+ - Margin-account actions on `MarginfiAccountWrapper`: `deposit`, `withdraw`, `borrow`, `repay`, `reload`
87
+
88
+ Prefer these helpers before assembling raw instructions manually.
89
+
90
+ ## 4. Flash-loan development notes
91
+
92
+ Official TS SDK docs describe `buildFlashLoanTx` as the preferred helper for building full flash-loan transactions.
93
+
94
+ The program docs describe flash loans as:
95
+
96
+ - `lending_account_start_flashloan`
97
+ - user instructions that consume the temporary liquidity
98
+ - `lending_account_end_flashloan`
99
+
100
+ Important implementation rules:
101
+
102
+ - Flash loans must begin and end in the same transaction.
103
+ - The end instruction must reference the correct end index.
104
+ - Nested or malformed flash-loan flows are rejected.
105
+ - Relevant program errors include `AccountInFlashloan`, `IllegalFlashloan`, `IllegalFlag`, and `NoFlashloanInProgress`.
106
+
107
+ If you need raw control, mirror the exact begin/end instruction ordering from the official docs.
108
+
109
+ ## 5. Rust CLI essentials
110
+
111
+ The Rust CLI docs describe profile-based configuration through `marginfi profile` and account or bank operations through `marginfi group` and `marginfi account` subcommands.
112
+
113
+ Representative CLI flows from the docs:
114
+
115
+ - profile and authority setup: `marginfi profile create`, `marginfi profile set`
116
+ - account flows: `marginfi account create`, `deposit`, `borrow`, `withdraw`, `repay`
117
+ - bank and admin flows: `marginfi group add-bank`, `configure-bank`, `collect-fees`, `setup-emissions`, `update-emissions`
118
+ - permissionless-bank creation: `marginfi group add-bank-permissionless`
119
+
120
+ Use the CLI when the job is operational, administrative, or quick to script from the terminal. Use the TS SDK when embedding marginfi into apps or bots.
121
+
122
+ ## 6. Permissionless banks and The Arena
123
+
124
+ The Arena docs describe a permissionless flow where developers can create marginfi banks from listed tokens.
125
+
126
+ Important configuration areas surfaced in the official docs:
127
+
128
+ - `asset_weight_init` / `asset_weight_maint`
129
+ - `liability_weight_init` / `liability_weight_maint`
130
+ - deposit and borrow limits
131
+ - interest-rate curve parameters such as optimal utilization, plateau rate, max rate, and fees
132
+ - `risk_tier`
133
+ - `operational_state`
134
+ - `oracle_setup`
135
+
136
+ The official TS docs also show `BankConfigOpt`, `InterestRateConfigOpt`, `OracleSetup`, `RiskTier`, and `OperationalState` in the permissionless-bank example.
137
+
138
+ When implementing bank creation:
139
+
140
+ - treat every config field as an explicit input
141
+ - validate the oracle source and required feed accounts
142
+ - keep listing-criteria and The Arena docs open while coding
143
+ - do not fabricate safe defaults for weights or limits
144
+
145
+ ## 7. Program instruction map
146
+
147
+ The `mfi-v2` docs expose the on-chain instruction set and typed errors.
148
+
149
+ Key instruction families to consult before raw program work:
150
+
151
+ - marginfi-group initialization and configuration
152
+ - bank creation and configuration
153
+ - margin-account creation
154
+ - deposit / withdraw
155
+ - borrow / repay
156
+ - emissions setup and update
157
+ - liquidate
158
+ - flash-loan begin / end
159
+ - account transfer flows
160
+
161
+ Useful error names exposed in the docs include:
162
+
163
+ - `Unauthorized`
164
+ - `BankNotFound`
165
+ - `MarginfiAccountNotFound`
166
+ - `OperationWithdrawOnly`
167
+ - `IllegalLiquidation`
168
+ - `IllegalFlashloan`
169
+ - `AccountInFlashloan`
170
+ - `NoFlashloanInProgress`
171
+ - `SwitchboardStalePrice`
172
+ - `CannotCloseOutstandingEmissions`
173
+
174
+ When surfacing failures to users, translate these into the failed business condition instead of echoing raw Solana logs only.
175
+
176
+ ## 8. Security and operational notes
177
+
178
+ The docs highlight:
179
+
180
+ - Halborn and Sec3 audits
181
+ - fuzz testing
182
+ - a bug-bounty program
183
+ - verifiable-build support via `solana-verify`
184
+
185
+ The official verification example is:
186
+
187
+ ```bash
188
+ solana-verify verify-from-repo -um --program-id MFv2hWf31Z9kbCa1snEPYctwafyhdvnV7FZnsebVacA https://github.com/mrgnlabs/marginfi-v2
189
+ ```
190
+
191
+ Use these references when the task touches deployment verification, trust assumptions, or upgrade review.
@@ -0,0 +1,31 @@
1
+ # Marginfi Official Source Index
2
+
3
+ Use this file to jump to the official page that matches the task.
4
+
5
+ ## Primary docs
6
+
7
+ - `https://docs.marginfi.com/`
8
+ - Read for current program IDs, group IDs, lookup-table references, and top-level navigation.
9
+ - `https://docs.marginfi.com/ts-sdk`
10
+ - Read for TypeScript integration, SDK classes, helper methods, and flash-loan or permissionless-bank examples.
11
+ - `https://docs.marginfi.com/rust-sdk`
12
+ - Read for CLI workflows, operator tasks, profiles, group commands, and bank administration.
13
+ - `https://docs.marginfi.com/protocol-design`
14
+ - Read for risk model, oracle rules, utilization-based interest design, and liquidation reasoning.
15
+ - `https://docs.marginfi.com/mfi-v2`
16
+ - Read for raw instruction names, account schemas, and error definitions.
17
+ - `https://docs.marginfi.com/the-arena`
18
+ - Read for permissionless-bank flows and links to listing criteria.
19
+
20
+ ## When to open which source
21
+
22
+ - App, bot, backend, or frontend integration: start with `ts-sdk`, then `protocol-design`.
23
+ - CLI or ops automation: start with `rust-sdk`.
24
+ - Custom Anchor or raw Solana instruction work: start with `mfi-v2`.
25
+ - Health checks, liquidation analysis, or risk explanations: start with `protocol-design`, then confirm relevant instruction behavior in `mfi-v2`.
26
+ - Permissionless bank creation: start with `the-arena`, then open `ts-sdk` or `rust-sdk` depending on the chosen toolchain.
27
+ - Address or deployment verification: start with the docs home page, then follow its linked source or verification references.
28
+
29
+ ## Working rule
30
+
31
+ If the request depends on a value that can change over time, reopen the live official page even if this skill already contains a summary.
@@ -0,0 +1,98 @@
1
+ ---
2
+ name: openclaw-configuration
3
+ description: Build, audit, and explain OpenClaw configuration from official documentation. Use when configuring `~/.openclaw/openclaw.json`, mapping config options, adjusting skills or secrets, generating validated snippets, or diagnosing config errors with `openclaw config`, `openclaw configure`, and `openclaw doctor`.
4
+ ---
5
+
6
+ # OpenClaw Configuration
7
+
8
+ ## Dependencies
9
+
10
+ - Required: none.
11
+ - Conditional: `answering-questions-with-research` when a request depends on newer OpenClaw docs than the bundled references cover.
12
+ - Optional: none.
13
+ - Fallback: If the local CLI is unavailable, work from the bundled references and clearly mark any runtime behavior that was not verified on the machine.
14
+
15
+ ## Standards
16
+
17
+ - Evidence: Verify the active config file, current values, and CLI diagnostics before editing.
18
+ - Execution: Prefer the smallest safe change; use `openclaw config` for narrow edits and direct JSON edits for broad restructures.
19
+ - Quality: Keep the file schema-valid, avoid plaintext secrets when a SecretRef or env var fits, and preserve unrelated valid settings.
20
+ - Output: Return exact file paths, touched keys, validation commands, and any restart or hot-reload caveats.
21
+
22
+ ## Goal
23
+
24
+ Help another agent configure OpenClaw safely, quickly, and with citations back to the official docs.
25
+
26
+ ## Workflow
27
+
28
+ ### 1. Classify the request
29
+
30
+ Decide whether the user needs:
31
+
32
+ - a config explanation
33
+ - a new starter config
34
+ - a targeted key update
35
+ - skills loading or per-skill env setup
36
+ - secrets or provider wiring
37
+ - validation or repair of a broken config
38
+
39
+ Assume the canonical config file is `~/.openclaw/openclaw.json` unless the environment proves otherwise.
40
+
41
+ ### 2. Choose the safest edit surface
42
+
43
+ - Use `openclaw onboard` or `openclaw configure` for guided setup.
44
+ - Use `openclaw config get/set/unset/validate` for precise path-based edits.
45
+ - Use direct JSON edits only when changing several related branches at once.
46
+ - If the local gateway is running, the Control UI config tab at `http://127.0.0.1:18789` can help inspect or edit the same schema-backed config.
47
+
48
+ ### 3. Load only the references you need
49
+
50
+ - Read `references/official-docs.md` first for the canonical doc map.
51
+ - Read `references/config-reference-map.md` when you need option names, CLI behavior, hot reload, skills config, env handling, or secrets rules.
52
+ - Read `references/best-practices.md` before producing a new config, touching credentials, or fixing a broken setup.
53
+
54
+ ### 4. Apply minimal, schema-safe changes
55
+
56
+ - Prefer `openclaw config set` for one-path edits.
57
+ - Prefer SecretRefs or env substitution over plaintext credentials.
58
+ - For skill-specific setup, use `skills.load.extraDirs`, `skills.entries.<skillKey>`, and per-skill `env` or `apiKey`.
59
+ - Do not invent unknown root keys; OpenClaw rejects schema-invalid config.
60
+
61
+ ### 5. Validate before finishing
62
+
63
+ - Run `openclaw config validate` after edits.
64
+ - If the gateway refuses to boot, run `openclaw doctor`.
65
+ - Use `openclaw doctor --repair` only after reviewing what it will change; the tool can back up the config and remove unknown keys.
66
+ - Call out whether the change should hot-apply or may still need a restart.
67
+
68
+ ### 6. Return a concise handoff
69
+
70
+ Always include:
71
+
72
+ - the file or keys changed
73
+ - the command or JSON snippet used
74
+ - the validation command
75
+ - any secret or env prereqs
76
+ - the official doc pages that justify the change
77
+
78
+ ## Common Tasks
79
+
80
+ ### Generate a starter config
81
+
82
+ Start from the official minimal or starter shape, then add only the channels, models, or skills the user actually needs.
83
+
84
+ ### Explain config options
85
+
86
+ Summarize the relevant branch and point back to the matching official page rather than dumping the entire reference.
87
+
88
+ ### Configure skills
89
+
90
+ Use `skills.load.extraDirs` for additional skill folders and `skills.entries.<skillKey>` for per-skill enablement, env vars, or `apiKey`.
91
+
92
+ ### Wire secrets
93
+
94
+ Prefer SecretRefs (`env`, `file`, or `exec`) for supported credential fields. Use plaintext only when the user explicitly wants a local-only quick setup and understands the tradeoff.
95
+
96
+ ### Repair a broken config
97
+
98
+ Run `openclaw config validate`, then `openclaw doctor`, and only then make the smallest correction that restores schema validity.
@@ -0,0 +1,4 @@
1
+ interface:
2
+ display_name: "OpenClaw Configuration"
3
+ short_description: "Configure and troubleshoot OpenClaw settings"
4
+ default_prompt: "Use $openclaw-configuration to explain, edit, validate, or troubleshoot OpenClaw configuration, including `~/.openclaw/openclaw.json`, `skills` settings, env vars, SecretRefs, and official OpenClaw CLI/config workflows."
@@ -0,0 +1,55 @@
1
+ # OpenClaw Configuration Best Practices
2
+
3
+ These rules are distilled from the official OpenClaw docs and adapted into a practical workflow.
4
+
5
+ ## Authoring rules
6
+
7
+ - Treat `~/.openclaw/openclaw.json` as the source of truth unless the environment proves otherwise.
8
+ - Prefer the smallest possible edit surface:
9
+ - one key: `openclaw config set`
10
+ - one subtree removal: `openclaw config unset`
11
+ - several coordinated edits: direct JSON edit plus validation
12
+ - Keep JSON structure conservative; OpenClaw rejects unknown keys.
13
+ - Use the configuration examples page as a baseline instead of inventing a new root layout.
14
+
15
+ ## Safety rules
16
+
17
+ - Never store production credentials in plaintext if a SecretRef or env var can be used.
18
+ - Avoid mixing plaintext and SecretRefs for the same credential path; the ref wins on supported fields and makes ownership clearer.
19
+ - Validate immediately after editing:
20
+ - `openclaw config validate`
21
+ - `openclaw doctor` when the gateway still behaves unexpectedly
22
+ - Use `openclaw doctor --repair` only when you are comfortable with automatic cleanup and backup behavior.
23
+
24
+ ## Environment rules
25
+
26
+ - Prefer `${VAR_NAME}` substitution for portable config shared across machines.
27
+ - Keep env var names uppercase to match the documented substitution pattern.
28
+ - Use `env.shellEnv.enabled` only when the missing-key import behavior is intentional and understood.
29
+ - Avoid scattering the same secret across the parent shell, local `.env`, and `~/.openclaw/.env`; keep precedence simple.
30
+
31
+ ## Skills rules
32
+
33
+ - Put extra skill roots in `skills.load.extraDirs` instead of hard-coding ad hoc discovery logic elsewhere.
34
+ - Use `skills.entries.<skillKey>.enabled` for explicit enable or disable state.
35
+ - Use `skills.entries.<skillKey>.env` for skill-local environment variables.
36
+ - Use `skills.entries.<skillKey>.apiKey` only when the skill expects a primary env-backed API key convenience field.
37
+ - Leave `skills.load.watch` enabled while iterating on local skills unless file-watch churn becomes a confirmed problem.
38
+ - If you set `skills.install.nodeManager`, remember the official docs still recommend Node as the runtime for the gateway itself.
39
+
40
+ ## Troubleshooting rules
41
+
42
+ - If the gateway stops booting after a config change, assume schema breakage first and validate before changing unrelated systems.
43
+ - When troubleshooting a credentialed path, inspect both the config branch and the SecretRef provider branch.
44
+ - When a user asks for "why did this stop working," capture the exact key path and the command used to validate it.
45
+ - For broken skill loading, check both `skills.load.extraDirs` and the effective `skillKey` mapping.
46
+
47
+ ## Recommended delivery format
48
+
49
+ When answering a user or editing a machine, return:
50
+
51
+ 1. the exact file or key path
52
+ 2. the change made
53
+ 3. the validation command
54
+ 4. the secret or env prerequisites
55
+ 5. the official docs used
@@ -0,0 +1,189 @@
1
+ # OpenClaw Config Reference Map
2
+
3
+ This file condenses the official OpenClaw configuration docs into a quick operator map.
4
+
5
+ ## Main file and edit surfaces
6
+
7
+ - Canonical file: `~/.openclaw/openclaw.json`
8
+ - Guided setup:
9
+ - `openclaw onboard`
10
+ - `openclaw configure`
11
+ - Precise edits:
12
+ - `openclaw config get <path>`
13
+ - `openclaw config set <path> <value>`
14
+ - `openclaw config unset <path>`
15
+ - `openclaw config validate`
16
+ - UI editing:
17
+ - Config tab in the local Control UI at `http://127.0.0.1:18789`
18
+ - Direct editing:
19
+ - safe for broader restructures, but validate immediately afterward
20
+
21
+ ## Validation and reload behavior
22
+
23
+ - OpenClaw enforces a strict schema.
24
+ - Unknown keys, bad types, or invalid values can prevent the gateway from starting.
25
+ - The root `$schema` string is the documented exception for editor schema metadata.
26
+ - When validation fails, the docs point to diagnostic commands such as:
27
+ - `openclaw doctor`
28
+ - `openclaw logs`
29
+ - `openclaw health`
30
+ - `openclaw status`
31
+ - The gateway watches `~/.openclaw/openclaw.json` and hot-applies many changes automatically.
32
+
33
+ ## CLI behavior worth remembering
34
+
35
+ ### Paths
36
+
37
+ - Dot notation works: `agents.defaults.workspace`
38
+ - Bracket notation works: `agents.list[0].tools.exec.node`
39
+
40
+ ### Value parsing
41
+
42
+ - `openclaw config set` parses JSON5 when possible.
43
+ - Use `--strict-json` when you want parsing to be required.
44
+ - Use strings intentionally for values such as heartbeat durations.
45
+
46
+ ### Assignment modes
47
+
48
+ - Value mode: plain path/value edit
49
+ - SecretRef builder mode: build a supported ref without hand-writing JSON
50
+ - Provider builder mode: build `secrets.providers.<alias>` entries
51
+ - Batch mode: apply several edits from a JSON payload or file
52
+
53
+ ## Official namespace map
54
+
55
+ The full reference documents these major sections:
56
+
57
+ - `channels`
58
+ - `agents`
59
+ - `session`
60
+ - `messages`
61
+ - `talk`
62
+ - `tools`
63
+ - custom providers and base URLs
64
+ - `skills`
65
+ - `plugins`
66
+ - `browser`
67
+ - `ui`
68
+ - `gateway`
69
+ - `hooks`
70
+ - canvas host
71
+ - discovery
72
+ - `environment`
73
+ - `secrets`
74
+ - auth storage
75
+ - logging
76
+ - CLI
77
+ - wizard
78
+ - identity
79
+ - `cron`
80
+ - media model template variables
81
+ - config includes via `$include`
82
+
83
+ Use the official full reference when you need the exact nested shape under one of these branches.
84
+
85
+ ## Environment variables
86
+
87
+ The gateway docs describe three non-inline sources:
88
+
89
+ - env vars from the parent process
90
+ - `.env` in the current working directory
91
+ - `~/.openclaw/.env` as a global fallback
92
+
93
+ Neither `.env` file overrides variables that are already present in the parent process.
94
+
95
+ The docs also describe config-side helpers:
96
+
97
+ - inline `env` sections
98
+ - optional shell env import via `env.shellEnv.enabled`
99
+ - config string substitution with `${VAR_NAME}`
100
+
101
+ Key rules called out by the docs:
102
+
103
+ - substitution targets uppercase variable names
104
+ - missing or empty values fail at load time
105
+ - use `$${VAR}` to escape a literal placeholder
106
+
107
+ ## Secrets and credential references
108
+
109
+ OpenClaw documents a common SecretRef shape:
110
+
111
+ ```json
112
+ {
113
+ "source": "env",
114
+ "provider": "default",
115
+ "id": "OPENAI_API_KEY"
116
+ }
117
+ ```
118
+
119
+ Supported ref sources in the docs:
120
+
121
+ - `env`
122
+ - `file`
123
+ - `exec`
124
+
125
+ Operational rules confirmed by the secrets docs:
126
+
127
+ - if a supported field has both plaintext and a ref, the ref takes precedence
128
+ - `openclaw secrets audit --check` is the default preflight
129
+ - `openclaw secrets configure` helps wire providers
130
+ - a final `openclaw secrets audit --check` confirms the setup
131
+
132
+ ## Skills configuration
133
+
134
+ The official skills config page documents these fields:
135
+
136
+ - `skills.allowBundled`
137
+ - `skills.load.extraDirs`
138
+ - `skills.load.watch`
139
+ - `skills.load.watchDebounceMs`
140
+ - `skills.install.preferBrew`
141
+ - `skills.install.nodeManager`
142
+ - `skills.entries.<skillKey>.enabled`
143
+ - `skills.entries.<skillKey>.env`
144
+ - `skills.entries.<skillKey>.apiKey`
145
+
146
+ Notes confirmed by the docs:
147
+
148
+ - `skills.entries` keys default to the skill name
149
+ - if a skill defines `metadata.openclaw.skillKey`, use that key instead
150
+ - watcher-driven skill changes are picked up on the next agent turn when watching is enabled
151
+
152
+ ## Example snippets to adapt
153
+
154
+ ### Minimal starter
155
+
156
+ ```json
157
+ {
158
+ "agents": {
159
+ "defaults": {
160
+ "workspace": "~/.openclaw/workspace"
161
+ }
162
+ },
163
+ "channels": {
164
+ "whatsapp": {
165
+ "allowFrom": ["+15555550123"]
166
+ }
167
+ }
168
+ }
169
+ ```
170
+
171
+ ### Custom skill directory plus per-skill env
172
+
173
+ ```json
174
+ {
175
+ "skills": {
176
+ "load": {
177
+ "extraDirs": ["~/skills", "~/.apollo-toolkit"]
178
+ },
179
+ "entries": {
180
+ "openclaw-configuration": {
181
+ "enabled": true,
182
+ "env": {
183
+ "OPENCLAW_CONFIG_PATH": "~/.openclaw/openclaw.json"
184
+ }
185
+ }
186
+ }
187
+ }
188
+ }
189
+ ```
@@ -0,0 +1,40 @@
1
+ # OpenClaw Official Config Docs
2
+
3
+ Last verified: 2026-03-20
4
+
5
+ Use this file as the entry map into the official OpenClaw documentation on `docs.openclaw.ai`.
6
+
7
+ ## Canonical pages
8
+
9
+ - Gateway configuration overview: `https://docs.openclaw.ai/gateway/configuration`
10
+ - Covers the main config file path, edit surfaces, strict validation, hot reload, env vars, and links to the full reference.
11
+ - Full configuration reference: `https://docs.openclaw.ai/gateway/configuration-reference`
12
+ - Covers the major top-level namespaces such as `channels`, `agents`, `tools`, `skills`, `plugins`, `gateway`, `secrets`, `cron`, and `$include`.
13
+ - Configuration examples: `https://docs.openclaw.ai/gateway/configuration-examples`
14
+ - Provides minimal and starter-shaped configs plus common deployment patterns.
15
+ - Skills config: `https://docs.openclaw.ai/tools/skills-config`
16
+ - Covers `skills.allowBundled`, `skills.load.*`, `skills.install.*`, and `skills.entries.<skillKey>`.
17
+ - Secrets management: `https://docs.openclaw.ai/gateway/secrets`
18
+ - Covers SecretRef structure, providers, precedence, audit flow, and secure credential handling.
19
+ - CLI config command: `https://docs.openclaw.ai/cli/config`
20
+ - Covers `openclaw config get/set/unset/validate`, path syntax, parsing rules, and SecretRef builder modes.
21
+ - CLI configure command: `https://docs.openclaw.ai/cli/configure`
22
+ - Covers the guided configuration wizard.
23
+ - CLI doctor command: `https://docs.openclaw.ai/cli/doctor`
24
+ - Covers diagnostics, repair behavior, backups, and environment checks.
25
+
26
+ ## Core facts confirmed from the official docs
27
+
28
+ - The canonical config file is `~/.openclaw/openclaw.json`.
29
+ - OpenClaw supports guided edits, CLI path edits, Control UI editing, and direct file editing.
30
+ - The gateway validates the config strictly against schema; unknown keys are rejected except for the root `$schema` metadata key.
31
+ - The gateway watches the config file and hot-applies many changes automatically.
32
+ - Secrets can be supplied through env vars, files, or exec-backed SecretRefs, depending on the field.
33
+
34
+ ## When to open which doc
35
+
36
+ - Need the exact field name or namespace: open the full reference.
37
+ - Need a starting snippet or pattern: open configuration examples.
38
+ - Need to load custom skills or set per-skill env: open skills config.
39
+ - Need to wire API keys safely: open secrets management plus CLI config.
40
+ - Need to repair a broken config: open gateway configuration plus CLI doctor.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@laitszkin/apollo-toolkit",
3
- "version": "2.5.0",
3
+ "version": "2.7.0",
4
4
  "description": "Apollo Toolkit npm installer for managed skill linking across Codex, OpenClaw, and Trae.",
5
5
  "license": "MIT",
6
6
  "author": "LaiTszKin",