Skip to content

Commit a3de1f5

Browse files
shakkernerdshakkernerd
committed
Skills: prefer active OpenClaw paths
1 parent 08d365f commit a3de1f5

12 files changed

Lines changed: 144 additions & 27 deletions

File tree

‎skills/canvas/SKILL.md‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -57,7 +57,7 @@ This is why localhost URLs don't work - the node receives the Tailscale hostname
5757

5858
## Configuration
5959

60-
In `~/.openclaw/openclaw.json`:
60+
In the active OpenClaw config file (`$OPENCLAW_CONFIG_PATH`, default `~/.openclaw/openclaw.json`):
6161

6262
```json
6363
{
@@ -106,7 +106,8 @@ HTML
106106
Check how your gateway is bound:
107107

108108
```bash
109-
cat ~/.openclaw/openclaw.json | jq '.gateway.bind'
109+
CONFIG_PATH="${OPENCLAW_CONFIG_PATH:-${OPENCLAW_STATE_DIR:-$HOME/.openclaw}/openclaw.json}"
110+
cat "$CONFIG_PATH" | jq '.gateway.bind'
110111
```
111112

112113
Then construct the URL:
@@ -156,7 +157,7 @@ canvas action:hide node:<node-id>
156157

157158
**Debug steps:**
158159

159-
1. Check server bind: `cat ~/.openclaw/openclaw.json | jq '.gateway.bind'`
160+
1. Check server bind: `CONFIG_PATH="${OPENCLAW_CONFIG_PATH:-${OPENCLAW_STATE_DIR:-$HOME/.openclaw}/openclaw.json}"; cat "$CONFIG_PATH" | jq '.gateway.bind'`
160161
2. Check what port canvas is on: `lsof -i :18793`
161162
3. Test URL directly: `curl http://<hostname>:18793/__openclaw__/canvas/<file>.html`
162163

‎skills/coding-agent/SKILL.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -263,7 +263,7 @@ git worktree remove /tmp/issue-99
263263
5. **--full-auto for building** - auto-approves changes
264264
6. **vanilla for reviewing** - no special flags needed
265265
7. **Parallel is OK** - run many Codex processes at once for batch work
266-
8. **NEVER start Codex in ~/.openclaw/** - it'll read your soul docs and get weird ideas about the org chart!
266+
8. **NEVER start Codex inside your OpenClaw state directory** (`$OPENCLAW_STATE_DIR`, default `~/.openclaw`) - it'll read your soul docs and get weird ideas about the org chart!
267267
9. **NEVER checkout branches in ~/Projects/openclaw/** - that's the LIVE OpenClaw instance!
268268

269269
---

‎skills/gh-issues/SKILL.md‎

Lines changed: 10 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -95,7 +95,8 @@ echo $GH_TOKEN
9595
If empty, read from config:
9696

9797
```
98-
cat ~/.openclaw/openclaw.json | jq -r '.skills.entries["gh-issues"].apiKey // empty'
98+
CONFIG_PATH="${OPENCLAW_CONFIG_PATH:-${OPENCLAW_STATE_DIR:-$HOME/.openclaw}/openclaw.json}"
99+
cat "$CONFIG_PATH" | jq -r '.skills.entries["gh-issues"].apiKey // empty'
99100
```
100101

101102
If still empty, check `/data/.clawdbot/openclaw.json`:
@@ -130,7 +131,7 @@ If in watch mode: Also filter out any issue numbers already in the PROCESSED_ISS
130131
Error handling:
131132

132133
- If curl returns an HTTP 401 or 403 → stop and tell the user:
133-
> "GitHub authentication failed. Please check your apiKey in the OpenClaw dashboard or in ~/.openclaw/openclaw.json under skills.entries.gh-issues."
134+
> "GitHub authentication failed. Please check your apiKey in the OpenClaw dashboard or in the active OpenClaw config path (`$OPENCLAW_CONFIG_PATH`, default `~/.openclaw/openclaw.json`) under `skills.entries.gh-issues`."
134135
- If the response is an empty array (after filtering) → report "No issues found matching filters" and stop (or loop back if in watch mode).
135136
- If curl fails or returns any other error → report the error verbatim and stop.
136137

@@ -228,7 +229,7 @@ Run these checks sequentially via exec:
228229
229230
If HTTP status is not 200, stop with:
230231
231-
> "GitHub authentication failed. Please check your apiKey in the OpenClaw dashboard or in ~/.openclaw/openclaw.json under skills.entries.gh-issues."
232+
> "GitHub authentication failed. Please check your apiKey in the OpenClaw dashboard or in the active OpenClaw config path (`$OPENCLAW_CONFIG_PATH`, default `~/.openclaw/openclaw.json`) under `skills.entries.gh-issues`."
232233
233234
5. **Check for existing PRs:**
234235
For each confirmed issue number N, run:
@@ -362,7 +363,8 @@ You are a focused code-fix agent. Your task is to fix a single GitHub issue and
362363
IMPORTANT: Do NOT use the gh CLI — it is not installed. Use curl with the GitHub REST API for all GitHub operations.
363364

364365
First, ensure GH_TOKEN is set. Check: `echo $GH_TOKEN`. If empty, read from config:
365-
GH_TOKEN=$(cat ~/.openclaw/openclaw.json 2>/dev/null | jq -r '.skills.entries["gh-issues"].apiKey // empty') || GH_TOKEN=$(cat /data/.clawdbot/openclaw.json 2>/dev/null | jq -r '.skills.entries["gh-issues"].apiKey // empty')
366+
CONFIG_PATH="${OPENCLAW_CONFIG_PATH:-${OPENCLAW_STATE_DIR:-$HOME/.openclaw}/openclaw.json}"
367+
GH_TOKEN=$(cat "$CONFIG_PATH" 2>/dev/null | jq -r '.skills.entries["gh-issues"].apiKey // empty') || GH_TOKEN=$(cat /data/.clawdbot/openclaw.json 2>/dev/null | jq -r '.skills.entries["gh-issues"].apiKey // empty')
366368

367369
Use the token in all GitHub API calls:
368370
curl -s -H "Authorization: Bearer $GH_TOKEN" -H "Accept: application/vnd.github+json" ...
@@ -397,7 +399,8 @@ export GH_TOKEN=$(node -e "const fs=require('fs'); const c=JSON.parse(fs.readFil
397399
If that fails, also try:
398400
```
399401
400-
export GH_TOKEN=$(cat ~/.openclaw/openclaw.json 2>/dev/null | node -e "const fs=require('fs');const d=JSON.parse(fs.readFileSync(0,'utf8'));console.log(d.skills?.entries?.['gh-issues']?.apiKey||'')")
402+
export CONFIG_PATH="${OPENCLAW_CONFIG_PATH:-${OPENCLAW_STATE_DIR:-$HOME/.openclaw}/openclaw.json}"
403+
export GH_TOKEN=$(cat "$CONFIG_PATH" 2>/dev/null | node -e "const fs=require('fs');const d=JSON.parse(fs.readFileSync(0,'utf8'));console.log(d.skills?.entries?.['gh-issues']?.apiKey||'')")
401404
402405
```
403406
Verify: echo "Token: ${GH_TOKEN:0:10}..."
@@ -730,7 +733,8 @@ You are a PR review handler agent. Your task is to address review comments on a
730733
IMPORTANT: Do NOT use the gh CLI — it is not installed. Use curl with the GitHub REST API for all GitHub operations.
731734

732735
First, ensure GH_TOKEN is set. Check: echo $GH_TOKEN. If empty, read from config:
733-
GH_TOKEN=$(cat ~/.openclaw/openclaw.json 2>/dev/null | jq -r '.skills.entries["gh-issues"].apiKey // empty') || GH_TOKEN=$(cat /data/.clawdbot/openclaw.json 2>/dev/null | jq -r '.skills.entries["gh-issues"].apiKey // empty')
736+
CONFIG_PATH="${OPENCLAW_CONFIG_PATH:-${OPENCLAW_STATE_DIR:-$HOME/.openclaw}/openclaw.json}"
737+
GH_TOKEN=$(cat "$CONFIG_PATH" 2>/dev/null | jq -r '.skills.entries["gh-issues"].apiKey // empty') || GH_TOKEN=$(cat /data/.clawdbot/openclaw.json 2>/dev/null | jq -r '.skills.entries["gh-issues"].apiKey // empty')
734738

735739
<config>
736740
Repository: {SOURCE_REPO}

‎skills/openai-whisper-api/SKILL.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -49,7 +49,7 @@ Defaults:
4949

5050
## API key
5151

52-
Set `OPENAI_API_KEY`, or configure it in `~/.openclaw/openclaw.json`. Optionally set `OPENAI_BASE_URL` (for example `http://127.0.0.1:51805/v1`) to use an OpenAI-compatible proxy or local gateway:
52+
Set `OPENAI_API_KEY`, or configure it in the active OpenClaw config file (`$OPENCLAW_CONFIG_PATH`, default `~/.openclaw/openclaw.json`). Optionally set `OPENAI_BASE_URL` (for example `http://127.0.0.1:51805/v1`) to use an OpenAI-compatible proxy or local gateway:
5353

5454
```json5
5555
{

‎skills/session-logs/SKILL.md‎

Lines changed: 18 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -38,7 +38,9 @@ Use this skill when the user asks about prior chats, parent conversations, or hi
3838

3939
## Location
4040

41-
Session logs live at: `~/.openclaw/agents/<agentId>/sessions/` (use the `agent=<id>` value from the system prompt Runtime line).
41+
Session logs live under the active state directory:
42+
`$OPENCLAW_STATE_DIR/agents/<agentId>/sessions/` (default: `~/.openclaw/agents/<agentId>/sessions/`).
43+
Use the `agent=<id>` value from the system prompt Runtime line.
4244

4345
- **`sessions.json`** - Index mapping session keys to session IDs
4446
- **`<session-id>.jsonl`** - Full conversation transcript per session
@@ -58,7 +60,9 @@ Each `.jsonl` file contains messages with:
5860
### List all sessions by date and size
5961

6062
```bash
61-
for f in ~/.openclaw/agents/<agentId>/sessions/*.jsonl; do
63+
AGENT_ID="<agentId>"
64+
SESSION_DIR="${OPENCLAW_STATE_DIR:-$HOME/.openclaw}/agents/$AGENT_ID/sessions"
65+
for f in "$SESSION_DIR"/*.jsonl; do
6266
date=$(head -1 "$f" | jq -r '.timestamp' | cut -dT -f1)
6367
size=$(ls -lh "$f" | awk '{print $5}')
6468
echo "$date $size $(basename $f)"
@@ -68,7 +72,9 @@ done | sort -r
6872
### Find sessions from a specific day
6973

7074
```bash
71-
for f in ~/.openclaw/agents/<agentId>/sessions/*.jsonl; do
75+
AGENT_ID="<agentId>"
76+
SESSION_DIR="${OPENCLAW_STATE_DIR:-$HOME/.openclaw}/agents/$AGENT_ID/sessions"
77+
for f in "$SESSION_DIR"/*.jsonl; do
7278
head -1 "$f" | jq -r '.timestamp' | grep -q "2026-01-06" && echo "$f"
7379
done
7480
```
@@ -94,7 +100,9 @@ jq -s '[.[] | .message.usage.cost.total // 0] | add' <session>.jsonl
94100
### Daily cost summary
95101

96102
```bash
97-
for f in ~/.openclaw/agents/<agentId>/sessions/*.jsonl; do
103+
AGENT_ID="<agentId>"
104+
SESSION_DIR="${OPENCLAW_STATE_DIR:-$HOME/.openclaw}/agents/$AGENT_ID/sessions"
105+
for f in "$SESSION_DIR"/*.jsonl; do
98106
date=$(head -1 "$f" | jq -r '.timestamp' | cut -dT -f1)
99107
cost=$(jq -s '[.[] | .message.usage.cost.total // 0] | add' "$f")
100108
echo "$date $cost"
@@ -122,7 +130,9 @@ jq -r '.message.content[]? | select(.type == "toolCall") | .name' <session>.json
122130
### Search across ALL sessions for a phrase
123131

124132
```bash
125-
rg -l "phrase" ~/.openclaw/agents/<agentId>/sessions/*.jsonl
133+
AGENT_ID="<agentId>"
134+
SESSION_DIR="${OPENCLAW_STATE_DIR:-$HOME/.openclaw}/agents/$AGENT_ID/sessions"
135+
rg -l "phrase" "$SESSION_DIR"/*.jsonl
126136
```
127137

128138
## Tips
@@ -135,5 +145,7 @@ rg -l "phrase" ~/.openclaw/agents/<agentId>/sessions/*.jsonl
135145
## Fast text-only hint (low noise)
136146

137147
```bash
138-
jq -r 'select(.type=="message") | .message.content[]? | select(.type=="text") | .text' ~/.openclaw/agents/<agentId>/sessions/<id>.jsonl | rg 'keyword'
148+
AGENT_ID="<agentId>"
149+
SESSION_DIR="${OPENCLAW_STATE_DIR:-$HOME/.openclaw}/agents/$AGENT_ID/sessions"
150+
jq -r 'select(.type=="message") | .message.content[]? | select(.type=="text") | .text' "$SESSION_DIR"/<id>.jsonl | rg 'keyword'
139151
```

‎skills/sherpa-onnx-tts/SKILL.md‎

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -63,26 +63,28 @@ Local TTS using the sherpa-onnx offline CLI.
6363

6464
## Install
6565

66-
1. Download the runtime for your OS (extracts into `~/.openclaw/tools/sherpa-onnx-tts/runtime`)
67-
2. Download a voice model (extracts into `~/.openclaw/tools/sherpa-onnx-tts/models`)
66+
1. Download the runtime for your OS (extracts into `$OPENCLAW_STATE_DIR/tools/sherpa-onnx-tts/runtime`, default `~/.openclaw/tools/sherpa-onnx-tts/runtime`)
67+
2. Download a voice model (extracts into `$OPENCLAW_STATE_DIR/tools/sherpa-onnx-tts/models`, default `~/.openclaw/tools/sherpa-onnx-tts/models`)
6868

69-
Update `~/.openclaw/openclaw.json`:
69+
Update the active OpenClaw config file (`$OPENCLAW_CONFIG_PATH`, default `~/.openclaw/openclaw.json`). Use a path inside your active state directory (`$OPENCLAW_STATE_DIR`, default `~/.openclaw`) for the runtime and model directories:
7070

7171
```json5
7272
{
7373
skills: {
7474
entries: {
7575
"sherpa-onnx-tts": {
7676
env: {
77-
SHERPA_ONNX_RUNTIME_DIR: "~/.openclaw/tools/sherpa-onnx-tts/runtime",
78-
SHERPA_ONNX_MODEL_DIR: "~/.openclaw/tools/sherpa-onnx-tts/models/vits-piper-en_US-lessac-high",
77+
SHERPA_ONNX_RUNTIME_DIR: "<state-dir>/tools/sherpa-onnx-tts/runtime",
78+
SHERPA_ONNX_MODEL_DIR: "<state-dir>/tools/sherpa-onnx-tts/models/vits-piper-en_US-lessac-high",
7979
},
8080
},
8181
},
8282
},
8383
}
8484
```
8585

86+
`<state-dir>` means your active `OPENCLAW_STATE_DIR` (default `~/.openclaw`).
87+
8688
The wrapper lives in this skill folder. Run it directly, or add the wrapper to PATH:
8789

8890
```bash

‎src/agents/skills.env-path-guidance.test.ts‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
import fs from "node:fs";
2+
import path from "node:path";
3+
import { describe, expect, it } from "vitest";
4+
5+
const REPO_ROOT = path.resolve(import.meta.dirname, "..", "..");
6+
7+
type GuidanceCase = {
8+
file: string;
9+
required?: string[];
10+
forbidden?: string[];
11+
};
12+
13+
const CASES: GuidanceCase[] = [
14+
{
15+
file: "skills/session-logs/SKILL.md",
16+
required: ["OPENCLAW_STATE_DIR"],
17+
forbidden: [
18+
"for f in ~/.openclaw/agents/<agentId>/sessions/*.jsonl",
19+
'rg -l "phrase" ~/.openclaw/agents/<agentId>/sessions/*.jsonl',
20+
],
21+
},
22+
{
23+
file: "skills/gh-issues/SKILL.md",
24+
required: ["OPENCLAW_CONFIG_PATH"],
25+
forbidden: ["cat ~/.openclaw/openclaw.json"],
26+
},
27+
{
28+
file: "skills/canvas/SKILL.md",
29+
required: ["OPENCLAW_CONFIG_PATH"],
30+
forbidden: ["cat ~/.openclaw/openclaw.json"],
31+
},
32+
{
33+
file: "skills/openai-whisper-api/SKILL.md",
34+
required: ["OPENCLAW_CONFIG_PATH"],
35+
},
36+
{
37+
file: "skills/sherpa-onnx-tts/SKILL.md",
38+
required: ["OPENCLAW_STATE_DIR", "OPENCLAW_CONFIG_PATH"],
39+
forbidden: [
40+
'SHERPA_ONNX_RUNTIME_DIR: "~/.openclaw/tools/sherpa-onnx-tts/runtime"',
41+
'SHERPA_ONNX_MODEL_DIR: "~/.openclaw/tools/sherpa-onnx-tts/models/vits-piper-en_US-lessac-high"',
42+
],
43+
},
44+
{
45+
file: "skills/coding-agent/SKILL.md",
46+
required: ["OPENCLAW_STATE_DIR"],
47+
forbidden: ["NEVER start Codex in ~/.openclaw/"],
48+
},
49+
];
50+
51+
describe("bundled skill env-path guidance", () => {
52+
it.each(CASES)(
53+
"keeps $file aligned with OPENCLAW env overrides",
54+
({ file, required, forbidden }) => {
55+
const content = fs.readFileSync(path.join(REPO_ROOT, file), "utf8");
56+
for (const needle of required ?? []) {
57+
expect(content).toContain(needle);
58+
}
59+
for (const needle of forbidden ?? []) {
60+
expect(content).not.toContain(needle);
61+
}
62+
},
63+
);
64+
});

‎src/cli/dns-cli.ts‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -153,7 +153,11 @@ export function registerDnsCli(program: Command) {
153153
}).trimEnd(),
154154
);
155155
defaultRuntime.log("");
156-
defaultRuntime.log(theme.heading("Recommended ~/.openclaw/openclaw.json:"));
156+
defaultRuntime.log(
157+
theme.heading(
158+
"Recommended config ($OPENCLAW_CONFIG_PATH, default ~/.openclaw/openclaw.json):",
159+
),
160+
);
157161
defaultRuntime.writeJson({
158162
gateway: { bind: "auto" },
159163
discovery: { wideArea: { enabled: true, domain: wideAreaDomain } },
@@ -248,7 +252,7 @@ export function registerDnsCli(program: Command) {
248252
defaultRuntime.log("");
249253
defaultRuntime.log(
250254
theme.muted(
251-
"Note: enable discovery.wideArea.enabled in ~/.openclaw/openclaw.json on the gateway and restart the gateway so it writes the DNS-SD zone.",
255+
"Note: enable discovery.wideArea.enabled in the active OpenClaw config ($OPENCLAW_CONFIG_PATH, default ~/.openclaw/openclaw.json) on the gateway and restart the gateway so it writes the DNS-SD zone.",
252256
),
253257
);
254258
}

‎src/cli/program/register.setup.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ import { hasExplicitOptions } from "../command-options.js";
1010
export function registerSetupCommand(program: Command) {
1111
program
1212
.command("setup")
13-
.description("Initialize ~/.openclaw/openclaw.json and the agent workspace")
13+
.description("Initialize the active OpenClaw config and agent workspace")
1414
.addHelpText(
1515
"after",
1616
() =>

‎src/cli/skills-cli.format.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -282,7 +282,7 @@ export function formatSkillInfo(
282282
` Save via CLI: ${formatCliCommand(`openclaw config set skills.entries.${safeSkillKey}.apiKey YOUR_KEY`)}`,
283283
);
284284
lines.push(
285-
` Stored in: ${theme.muted("~/.openclaw/openclaw.json")} ${theme.muted(`(skills.entries.${safeSkillKey}.apiKey)`)}`,
285+
` Stored in: ${theme.muted("$OPENCLAW_CONFIG_PATH")} ${theme.muted("(default: ~/.openclaw/openclaw.json)")}`,
286286
);
287287
}
288288

0 commit comments

Comments
 (0)