/raven-self-config

name: raven-self-config
description: Viewing and changing your own settings (raven_config), mostly connecting agents and chat apps; also where to look when one of your abilities is missing or fails.
metadata: {"raven":{"emoji":"🛠️","always":true,"inject":"description","requires":{"tools":["raven_config"]}}}

Configuring Raven itself

`raven_config` is the only way you change Raven's configuration. Never edit `config.json`, an agent's `.env`, or anything under `~/.raven` with file or shell tools: those writes skip validation, skip the user's confirmation, and a config that fails validation stops Raven from starting.

Raven's source code, logs and config files are not a manual. To find out what can be configured or why something is set up the way it is, use `raven_config` and nothing else: do not grep or read Raven's source, its logs, `~/.raven` or another Raven's files. If `raven_config` has no setting for it, tell the user it cannot be changed from here (and where, if Settings has it); that answer is correct and complete.

Suspect configuration when something fails or is missing

Most questions about settings are not phrased as settings. Treat these as configuration questions and look before you answer:

| The user says or you see | Look at | |---|---| | A sub-agent failed, errored, or "is not there" (`Raven-Research` failed, no Codex) | `describe subagents.<name>`: added? enabled? `status`, `last_test`, `needs_auth`, `missing_program` say why. An external agent's own problem you then fix yourself (see Sub-agents); Raven's source and logs are not where the answer is | | A tool you would use is not in your tool list, or the user asks whether you can do something (generate images, search the web, speak) | `describe`: a capability that is off shows `not set` with what that means (image, speech and video generation, web search). Answer "yes, once it is configured" and offer to set it up, never a flat "I can't". Handing the work to a sub-agent that has the tool is fine; say your own is not configured | | Commands time out, turns stop early, context is forgotten, or the user asks whether you have a limit | `tools.exec.timeout`, `agents.defaults.maxToolIterations`, `agents.defaults.contextWindowTokens`. Read the value before answering; do not answer from what you believe about yourself | | "I message you on Telegram/Feishu/... and you don't answer" | `describe channels.<name>`: enabled? `allowFrom` includes them? | | A link to GitHub, Notion, Linear, Jira, Slack, Google Drive ... | Not a setting: the `plugin` tool. `plugin list` to see if it is connected; if not, `plugin find` and offer to connect it, and say what connecting gets them (private repos, write access). Reading a public page instead is fine, but the reply still says it is not connected and offers the connection |

Then say what you found in one or two sentences, and offer the fix. Do not change anything the user did not ask for; a diagnosis is not permission. If the cause is a missing key, say which one and where the user enters it.

Find before you change

`describe` with no path returns every setting with its current value, one line each, plus the channels and sub-agents. One call is enough to find the path and see what it is set to now; do not walk section by section and do not `get` what the index already shows.

• `describe <words>` searches (English words: `describe image generation`),

and a path that does not exist answers with the closest ones. Use those; do not invent paths.

• `describe <path>` gives one setting's notes and value format;

`describe channels.<name>` and `describe subagents.<name>` give one instance's fields and health.

• Two settings with similar names are usually two different things

(`tools.web.search.provider` picks a vendor; `tools.web.providers.<vendor>.apiKey` is that vendor's key).

Connecting something ("connect X", "接 X", "用 X")

X is one of three kinds; the `describe` index shows the last two:

• A service with an account (GitHub, Notion, Linear, Slack, Google Drive ...):

a plugin. `plugin find <name>`, then offer `plugin connect`.

• An agent (Codex, Claude Code, OpenClaw, Gemini ...): a sub-agent. It is in

the `[subagents]` part of the index, often as a preset marked `not added`: `add subagents {"preset": "<preset>"}`. One that is not listed cannot be connected from here; say so. `add` runs the agent once and says exactly what is wrong, so try it first and diagnose only what it refuses.

• A chat app you want to talk to Raven from (Telegram, Feishu, WeChat ...): a

channel. `describe channels.<name>`, then set its credentials and `enabled`.

Change

• `set <path>` with `value` as JSON: `true`, `30`, `"eco"`, `["a","b"]`,

`{"provider": "openrouter", "model": "anthropic/claude-sonnet-5"}`, `null`.

• List settings (`tools.disabledTools`, `skillForge.blocklist`,

`playbooks.disabled`, `channels.<name>.allowFrom`) are replaced whole: take the current list from the index, change it, send all of it back. `describe tools.disabledTools` lists the tool names there are.

• `unset <path>` returns a setting to its default.
• A change is confirmed by the user unless their approval mode lets it

through (full access; smart mode's reviewer, except for sensitive settings). State in one sentence what you are about to change and why before calling; if they refuse, do not look for another way.

• Several settings that belong to one request go in one call, so the user

confirms them on one card: `set` with no `path` and `value` as an object, `{"tools.web.search.provider": "tavily", "tools.web.providers.tavily.apiKey": null}`. Every value is checked before anything is written. Channels and sub-agents are changed one call each.

When it takes effect

The reply to `set` says it; repeat it to the user in plain words.

| `takes_effect` says | What to tell the user | |---|---| | next turn | Active from their next message. | | at once | Already active. | | gatew