@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.
- package/AGENTS.md +4 -0
- package/CHANGELOG.md +23 -0
- package/README.md +4 -0
- package/codex-memory-manager/SKILL.md +2 -0
- package/fix-github-issues/SKILL.md +5 -3
- package/jupiter-development/SKILL.md +89 -0
- package/jupiter-development/agents/openai.yaml +4 -0
- package/jupiter-development/references/official-docs.md +157 -0
- package/learn-skill-from-conversations/SKILL.md +13 -2
- package/marginfi-development/LICENSE +21 -0
- package/marginfi-development/README.md +31 -0
- package/marginfi-development/SKILL.md +125 -0
- package/marginfi-development/agents/openai.yaml +4 -0
- package/marginfi-development/references/official-development-notes.md +191 -0
- package/marginfi-development/references/source-index.md +31 -0
- package/openclaw-configuration/SKILL.md +98 -0
- package/openclaw-configuration/agents/openai.yaml +4 -0
- package/openclaw-configuration/references/best-practices.md +55 -0
- package/openclaw-configuration/references/config-reference-map.md +189 -0
- package/openclaw-configuration/references/official-docs.md +40 -0
- package/package.json +1 -1
- package/solana-development/SKILL.md +89 -0
- package/solana-development/agents/openai.yaml +4 -0
- package/solana-development/references/official-solana-rust.md +199 -0
|
@@ -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.
|